Release 10.1A: OpenEdge Application Server:
Developing AppServer Applications

Understanding proxy persistent procedure handles

When you execute a remote persistent procedure in a Progress 4GL client application, two persistent procedure handles are created: one within the client application session and another separate handle within the AppServer session where the persistent procedure is created. OpenEdge internally maintains a mapping between the two handles. The handle within the client application is a proxy persistent procedure handle, and its PROXY attribute and PERSISTENT attribute are set to TRUE. The corresponding handle within the AppServer agent is a remote persistent procedure handle, and its REMOTE attribute and PERSISTENT attribute are set to TRUE.

For more information on the relationship between proxy and remote persistent procedure handles, see the information on procedure handles in Chapter 4, " Design and Implementation Considerations."

Accessing proxy persistent procedure handles

You can obtain access to the proxy persistent procedure handle in the client using the SET option of the RUN statement, which returns the proxy persistent procedure handle value to the HANDLE variable you specify.

You can also access all proxy persistent procedure handles that are currently active for an AppServer connection by returning the value of the FIRST-PROCEDURE attribute or the LAST-PROCEDURE attribute on the server handle for the connection. You can then use the NEXT-SIBLING or PREV-SIBLING attributes on the resulting procedure handle to navigate the list of active proxy persistent procedure handles. For example:

DEFINE VARIABLE hProxy AS HANDLE NO-UNDO. DEFINE VARIABLE hServer AS HANDLE NO-UNDO. /* Create server handle for hServer and connect to an AppServer. */ /* Call remote persistent procedures on the AppServer.           */ hProxy = hServer:FIRST-PROCEDURE. /* First proxy handle */ /* Display the pathname of the file that contains the remote procedure */ /* active on the AppServer for each proxy persistent procedure handle. */ DO WHILE NOT hProxy = hServer:LAST-PROCEDURE:    DISPLAY hProxy:FILE-NAME.    hProxy = hProxy:NEXT-SIBLING. END. DISPLAY hProxy:FILE-NAME. /* Procedure pathname for last proxy handle */

Comparing proxy and local persistent procedure handles

Unlike the values of a procedure handle variable and the THIS-PROCEDURE system handle that reference the same local persistent procedure context, the proxy persistent procedure handle in a client session and the corresponding remote persistent procedure handle in the AppServer agent are truly separate handles. For example, setting the PRIVATE-DATA attribute on a proxy persistent procedure handle has no effect on the PRIVATE-DATA attribute of the corresponding remote persistent procedure handle.

However, note that the OpenEdge mapping between a proxy persistent procedure handle and its corresponding remote persistent procedure handle allows you to execute remote internal procedures and user-defined functions using the proxy handle. For more information, see the "Running and managing remote procedures" section.